home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / doc / cryptsetup / README.keyctl < prev    next >
Encoding:
Text File  |  2011-03-09  |  3.1 KB  |  99 lines
  1. decrypt_keyctl
  2. ==============
  3.  
  4. A passphrase caching script to be used in /etc/crypttab on Debian and Ubuntu.
  5. When there are multiple cryptsetup (either plain or LUKS) volumes with the same
  6. passphrase, it is an unnecessary task to input the passphrase more than once.
  7.  
  8. Just add this script as keyscript to your /etc/crypttab and it will cache the
  9. passphrase of all cryptab entries with the same identifier.
  10.  
  11. Either copy decrypt_keyctl into the default search path for keyscripts from
  12. cryptsetup /lib/cryptdisks/scripts/. So you can just write keyscript=decrypt_keyctl
  13. in /etc/crypttab, or use a random path of your choice and give the full path
  14. e.g keyscript=/sbin/decrypt_keyctl.
  15.  
  16.  
  17. Requirements
  18. ------------
  19.  
  20.     - Debian cryptsetup package with /etc/crypttab handling and keyscript option
  21.         - Tested with Debian Lenny, Squeeze and Sid
  22.     - Installed and working keyutils package (keyctl)
  23.         - Needs CONFIG_KEYS=y in your kernel configuration
  24.  
  25.  
  26. What For?
  27. ---------
  28.  
  29. The current state for dm-crypt in Linux is that it is single threaded, thus
  30. every dm-crypt mapping only uses a single core for crypto operations.
  31. To use the full power of your many-core processor it is thus necessary to split
  32. the dm-crypt device. For Linux software raid arrays the easiest segmentation is to
  33. just put the dm-crypt layer below the software raid layer.
  34.  
  35. But with a 5 disk raid5 it is a rather daunting task to input the passphrase five
  36. times.
  37. This is what this keyscripts solve for you.
  38.  
  39.  
  40. Usage
  41. -----
  42.  
  43. Best shown by example:
  44.     - 5 disks
  45.     - Linux software raid5
  46.  
  47. Layer:
  48.       sda             sdb            sdc ... sde
  49.     +-----------+   +-----------+
  50.     | LUKS      |   | LUKS      |
  51.     | +-------+ |   | +-------+ |
  52.     | | RAID5 | |   | | RAID5 | |
  53.     | | ...   | |   | | ...   | |
  54.  
  55. Crypttab Entries:
  56.  
  57. <target>    <source>    <keyfile>        <options>
  58. sda_crypt   /dev/sda2   main_data_raid   luks,keyscript=decrypt_keyctl
  59. sdb_crypt   /dev/sdb2   main_data_raid   luks,keyscript=decrypt_keyctl
  60. ...
  61. sde_crypt   /dev/sde2   main_data_raid   luks,keyscript=decrypt_keyctl
  62.  
  63.  
  64. How does it work
  65. ----------------
  66.  
  67. Crypttab Interface:
  68. A keyscript is added to options including a keyfile definition as third
  69. parameter in the crypttab file. The keyscript is called with the keyfile as the
  70. first and only parameter. Additionally there are a few environment variables
  71. set but currently are not used by this keyscript (man 5 crypttab for exact
  72. description).
  73.  
  74. Keyscript:
  75. Keyctl_keyscript uses the Linux kernel keyring facility to securly cache
  76. passphrases between multiple invocations.
  77. The keyfile parameter from cryptab is used to find the same passphrase between
  78. multiple invocations.
  79.  
  80. Currently the cache timeout is 60 seconds and not configurable (please report a
  81. bug if it is too low for you).
  82.  
  83.  
  84. Problems
  85. --------
  86.  
  87.     - Passphrase is piped between processes and could end up in unsecured
  88.         memory, thus later swapped to disk!
  89.         => Use of cryptoswap recommend!
  90.  
  91.  
  92. Hints
  93. -----
  94.  
  95. To remove all traces of this keyscript you may want to cleanup the keyring
  96. completely with the following command afterwards:
  97.     sudo keyctl clear @u
  98.  
  99.